@qualisero/openapi-endpoint 0.12.3 → 0.13.2

package/dist/openapi-mutation.d.ts

@@ -1,118 +1,86 @@
 import { type ComputedRef, type Ref, type MaybeRefOrGetter } from 'vue';
-import { type GetPathParameters, type QMutationVars, type GetResponseData, type QMutationOptions, Operations, GetRequestBody } from './types';
+import { type ApiPathParams, type ApiPathParamsInput, type ApiResponse, type QMutationOptions, type MutateFn, type MutateAsyncFn, Operations } from './types';
 import { type OpenApiHelpers } from './openapi-helpers';
 import { type AxiosResponse } from 'axios';
-export type EndpointMutationReturn<Ops extends Operations<Ops>, Op extends keyof Ops> = ReturnType<typeof useEndpointMutation<Ops, Op>>;
 /**
- * Composable for performing a strictly typed OpenAPI mutation operation using Vue Query.
- * Ensures the operation is a mutation (POST/PUT/PATCH/DELETE) at runtime.
- * Returns a reactive mutation object, including helpers for query key and enabled state.
+ * Return type of `useMutation` (created via `useOpenApi`).
  *
- * NOTE: By default, the mutation will automatically update cache with returned data and reload
- * any matching GET queries for the same path.
+ * Reactive mutation result with automatic cache management and helpers.
  *
- * @template T OperationId type representing the OpenAPI operation.
- * @param operationId The OpenAPI operation ID to mutate.
- * @param pathParams Optional path parameters for the endpoint, can be reactive.
- * @param options Optional mutation options, including Vue Query options and custom axios options:
- *   - 'dontUpdateCache': If true, will not update cache with returned data (default: false)
- *   - 'dontInvalidate': If true, will not invalidate matching GET queries (default: false)
- *  - 'invalidateOperations': List of additional OperationIds to invalidate after mutation (can also be a map of OperationId to path parameters)
- * - 'refetchEndpoints': List of additional EndpointQueryReturn objects to refetch after mutation
- *   - `axiosOptions`: Custom axios request options (e.g., headers, params)
- *   - All properties from {@link UseMutationOptions} (from @tanstack/vue-query)
- * @throws Error if the operation is not a mutation operation.
+ * All properties are reactive (ComputedRef/Ref) and auto-unwrap in Vue templates.
+ *
+ * @template Ops - The operations type from your OpenAPI specification
+ * @template Op - The operation key from your operations type
+ *
+ * @example
+ * ```typescript
+ * const mutation = api.useMutation('createPet')
+ *
+ * // Reactive properties
+ * if (mutation.isPending.value) console.log('Saving...')
+ * if (mutation.isSuccess.value) console.log('Created:', mutation.data.value)
+ *
+ * // Execute
+ * mutation.mutate({ data: { name: 'Fluffy' } })
+ * await mutation.mutateAsync({ data: { name: 'Fluffy' } })
+ * ```
+ *
+ * @group Types
+ */
+export interface EndpointMutationReturn<Ops extends Operations<Ops>, Op extends keyof Ops> {
+    /** The Axios response (undefined until mutation completes). */
+    data: ComputedRef<AxiosResponse<ApiResponse<Ops, Op>> | undefined>;
+    /** The error if the mutation failed. */
+    error: Ref<Error | null>;
+    /** True while the mutation is in progress. */
+    isPending: Ref<boolean>;
+    /** True when the mutation succeeded. */
+    isSuccess: Ref<boolean>;
+    /** True when the mutation failed. */
+    isError: Ref<boolean>;
+    /** Execute the mutation (non-blocking). */
+    mutate: MutateFn<Ops, Op>;
+    /** Execute the mutation and wait for the response. */
+    mutateAsync: MutateAsyncFn<Ops, Op>;
+    /** Reset the mutation state. */
+    reset: () => void;
+    /** Whether the mutation can execute (path parameters resolved). */
+    isEnabled: ComputedRef<boolean>;
+    /** The resolved path parameters. */
+    pathParams: ComputedRef<ApiPathParams<Ops, Op>>;
+    /** Additional path parameters that can be provided at mutation time. */
+    extraPathParams: Ref<ApiPathParams<Ops, Op>>;
+}
+/**
+ * Execute a type-safe mutation (POST/PUT/PATCH/DELETE) with automatic cache updates.
+ *
+ * Ensures the operation is a mutation at runtime and returns a reactive mutation object
+ * with helpers for path resolution and cache invalidation.
+ *
+ * NOTE: By default, the mutation updates cache for PUT/PATCH and invalidates matching
+ * GET queries for the same path.
+ *
+ * @template Ops - The operations type from your OpenAPI specification
+ * @template Op - The operation key from your operations type
+ * @param operationId - The OpenAPI operation ID to mutate
+ * @param h - OpenAPI helpers (internal), provided by useOpenApi
+ * @param pathParams - Path parameters (can be reactive). Omit for operations without path params.
+ * @param options - Mutation options (dontInvalidate, refetchEndpoints, etc.)
+ *   - `dontUpdateCache`: Skip cache update for PUT/PATCH responses
+ *   - `dontInvalidate`: Skip invalidating matching queries
+ *   - `invalidateOperations`: Additional operation IDs to invalidate (array or map of params)
+ *   - `refetchEndpoints`: Additional query results to refetch
+ *   - `queryParams`: Query string parameters (operation-specific)
+ *   - `axiosOptions`: Custom axios request options (headers, params, etc.)
+ *   - Plus all {@link UseMutationOptions} from @tanstack/vue-query
+ * @throws Error if the operation is not a mutation operation
  * @returns Mutation object with
- *   - `data`: ComputedRef of response data.
- *   - `isEnabled`: ComputedRef indicating if mutation can be executed (path resolved).
- *   - `extraPathParams`: Ref to set of additional path parameters when calling mutate.
- *   - `mutate` and `mutateAsync`: Functions to trigger the mutation, taking an object with:
- *     - `data`: The request body data for the mutation.
- *     - `pathParams`: Optional additional path parameters for the mutation.
- *     - `axiosOptions`: Optional axios configuration overrides for this specific mutation call.
- *    - `dontUpdateCache`, `dontInvalidate`, `invalidateOperations`, `refetchEndpoints`: Same as options, but can be set per-mutation.
- *   - All other properties and methods from the underlying Vue Query mutation object.
+ *   - `mutate(vars)` / `mutateAsync(vars)` to trigger the mutation
+ *   - `data`: ComputedRef of Axios response data
+ *   - `isEnabled`: ComputedRef indicating if mutation can execute (path resolved)
+ *   - `extraPathParams`: Ref to set additional path params at call time
+ *   - `pathParams`: Resolved path params as a computed ref
  */
 export declare function useEndpointMutation<Ops extends Operations<Ops>, Op extends keyof Ops>(operationId: Op, h: OpenApiHelpers<Ops, Op>, // helpers
-pathParamsOrOptions?: MaybeRefOrGetter<GetPathParameters<Ops, Op> | null | undefined> | QMutationOptions<Ops, Op>, optionsOrNull?: QMutationOptions<Ops, Op>): {
-    data: ComputedRef<AxiosResponse<GetResponseData<Ops, Op>> | undefined>;
-    isEnabled: ComputedRef<boolean>;
-    extraPathParams: Ref<GetPathParameters<Ops, Op>, GetPathParameters<Ops, Op>>;
-    pathParams: ComputedRef<GetPathParameters<Ops, Op>>;
-    context: Ref<unknown, unknown>;
-    error: Ref<null, null>;
-    isError: Ref<false, false>;
-    isPending: Ref<false, false>;
-    isSuccess: Ref<false, false>;
-    status: Ref<"idle", "idle">;
-    failureCount: Ref<number, number>;
-    failureReason: Ref<Error | null, Error | null>;
-    isPaused: Ref<boolean, boolean>;
-    variables: Ref<undefined, undefined>;
-    isIdle: Ref<true, true>;
-    submittedAt: Ref<number, number>;
-    mutate: (variables: GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, options?: import("@tanstack/query-core").MutateOptions<AxiosResponse<any, any, {}>, Error, GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, unknown> | undefined) => void;
-    mutateAsync: import("@tanstack/query-core").MutateFunction<AxiosResponse<any, any, {}>, Error, GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, unknown>;
-    reset: import("@tanstack/query-core").MutationObserverResult<TData, TError, TVariables, TOnMutateResult>["reset"];
-} | {
-    data: ComputedRef<AxiosResponse<GetResponseData<Ops, Op>> | undefined>;
-    isEnabled: ComputedRef<boolean>;
-    extraPathParams: Ref<GetPathParameters<Ops, Op>, GetPathParameters<Ops, Op>>;
-    pathParams: ComputedRef<GetPathParameters<Ops, Op>>;
-    context: Ref<unknown, unknown>;
-    error: Ref<null, null>;
-    isError: Ref<false, false>;
-    isPending: Ref<true, true>;
-    isSuccess: Ref<false, false>;
-    status: Ref<"pending", "pending">;
-    failureCount: Ref<number, number>;
-    failureReason: Ref<Error | null, Error | null>;
-    isPaused: Ref<boolean, boolean>;
-    variables: import("@vue/shared").IfAny<GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, Ref<GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>>, [GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>] extends [Ref<any, any>] ? Ref<any, any> & (GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>) : Ref<GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>>>;
-    isIdle: Ref<false, false>;
-    submittedAt: Ref<number, number>;
-    mutate: (variables: GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, options?: import("@tanstack/query-core").MutateOptions<AxiosResponse<any, any, {}>, Error, GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, unknown> | undefined) => void;
-    mutateAsync: import("@tanstack/query-core").MutateFunction<AxiosResponse<any, any, {}>, Error, GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, unknown>;
-    reset: import("@tanstack/query-core").MutationObserverResult<TData, TError, TVariables, TOnMutateResult>["reset"];
-} | {
-    data: ComputedRef<AxiosResponse<GetResponseData<Ops, Op>> | undefined>;
-    isEnabled: ComputedRef<boolean>;
-    extraPathParams: Ref<GetPathParameters<Ops, Op>, GetPathParameters<Ops, Op>>;
-    pathParams: ComputedRef<GetPathParameters<Ops, Op>>;
-    context: Ref<unknown, unknown>;
-    error: Ref<Error, Error>;
-    isError: Ref<true, true>;
-    isPending: Ref<false, false>;
-    isSuccess: Ref<false, false>;
-    status: Ref<"error", "error">;
-    failureCount: Ref<number, number>;
-    failureReason: Ref<Error | null, Error | null>;
-    isPaused: Ref<boolean, boolean>;
-    variables: import("@vue/shared").IfAny<GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, Ref<GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>>, [GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>] extends [Ref<any, any>] ? Ref<any, any> & (GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>) : Ref<GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>>>;
-    isIdle: Ref<false, false>;
-    submittedAt: Ref<number, number>;
-    mutate: (variables: GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, options?: import("@tanstack/query-core").MutateOptions<AxiosResponse<any, any, {}>, Error, GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, unknown> | undefined) => void;
-    mutateAsync: import("@tanstack/query-core").MutateFunction<AxiosResponse<any, any, {}>, Error, GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, unknown>;
-    reset: import("@tanstack/query-core").MutationObserverResult<TData, TError, TVariables, TOnMutateResult>["reset"];
-} | {
-    data: ComputedRef<AxiosResponse<GetResponseData<Ops, Op>> | undefined>;
-    isEnabled: ComputedRef<boolean>;
-    extraPathParams: Ref<GetPathParameters<Ops, Op>, GetPathParameters<Ops, Op>>;
-    pathParams: ComputedRef<GetPathParameters<Ops, Op>>;
-    context: Ref<unknown, unknown>;
-    error: Ref<null, null>;
-    isError: Ref<false, false>;
-    isPending: Ref<false, false>;
-    isSuccess: Ref<true, true>;
-    status: Ref<"success", "success">;
-    failureCount: Ref<number, number>;
-    failureReason: Ref<Error | null, Error | null>;
-    isPaused: Ref<boolean, boolean>;
-    variables: import("@vue/shared").IfAny<GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, Ref<GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>>, [GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>] extends [Ref<any, any>] ? Ref<any, any> & (GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>) : Ref<GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>>>;
-    isIdle: Ref<false, false>;
-    submittedAt: Ref<number, number>;
-    mutate: (variables: GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, options?: import("@tanstack/query-core").MutateOptions<AxiosResponse<any, any, {}>, Error, GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, unknown> | undefined) => void;
-    mutateAsync: import("@tanstack/query-core").MutateFunction<AxiosResponse<any, any, {}>, Error, GetRequestBody<Ops, Op> extends never ? void | QMutationVars<Ops, Op> : QMutationVars<Ops, Op>, unknown>;
-    reset: import("@tanstack/query-core").MutationObserverResult<TData, TError, TVariables, TOnMutateResult>["reset"];
-};
+pathParams?: MaybeRefOrGetter<ApiPathParamsInput<Ops, Op> | null | undefined>, options?: QMutationOptions<Ops, Op>): EndpointMutationReturn<Ops, Op>;
 //# sourceMappingURL=openapi-mutation.d.ts.map

package/dist/openapi-mutation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi-mutation.d.ts","sourceRoot":"","sources":["../src/openapi-mutation.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,WAAW,EAAE,KAAK,GAAG,EAAE,KAAK,gBAAgB,EAAE,MAAM,KAAK,CAAA;AAG/F,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EAErB,UAAU,EACV,cAAc,EACf,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,OAAO,CAAA;AAE1C,MAAM,MAAM,sBAAsB,CAAC,GAAG,SAAS,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,MAAM,GAAG,IAAI,UAAU,CAChG,OAAO,mBAAmB,CAAC,GAAG,EAAE,EAAE,CAAC,CACpC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,SAAS,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,MAAM,GAAG,EACnF,WAAW,EAAE,EAAE,EACf,CAAC,EAAE,cAAc,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,UAAU;AACtC,mBAAmB,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,gBAAgB,CAAC,GAAG,EAAE,EAAE,CAAC,EACjH,aAAa,CAAC,EAAE,gBAAgB,CAAC,GAAG,EAAE,EAAE,CAAC;UA2LhB,WAAW,CAAC,aAAa,CAAC,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;UAAhE,WAAW,CAAC,aAAa,CAAC,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;UAAhE,WAAW,CAAC,aAAa,CAAC,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;UAAhE,WAAW,CAAC,aAAa,CAAC,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC;;;;;;;;;;;;;;;;;;;EAK1F"}
+{"version":3,"file":"openapi-mutation.d.ts","sourceRoot":"","sources":["../src/openapi-mutation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,WAAW,EAAE,KAAK,GAAG,EAAE,KAAK,gBAAgB,EAAE,MAAM,KAAK,CAAA;AAGtF,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EAEvB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EAErB,KAAK,QAAQ,EACb,KAAK,aAAa,EAElB,UAAU,EACX,MAAM,SAAS,CAAA;AAQhB,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,OAAO,CAAA;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,sBAAsB,CAAC,GAAG,SAAS,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,MAAM,GAAG;IACvF,+DAA+D;IAC/D,IAAI,EAAE,WAAW,CAAC,aAAa,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;IAElE,wCAAwC;IACxC,KAAK,EAAE,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,CAAA;IAExB,8CAA8C;IAC9C,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAA;IAEvB,wCAAwC;IACxC,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAA;IAEvB,qCAAqC;IACrC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAA;IAErB,2CAA2C;IAC3C,MAAM,EAAE,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;IAEzB,sDAAsD;IACtD,WAAW,EAAE,aAAa,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;IAEnC,gCAAgC;IAChC,KAAK,EAAE,MAAM,IAAI,CAAA;IAEjB,mEAAmE;IACnE,SAAS,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;IAE/B,oCAAoC;IACpC,UAAU,EAAE,WAAW,CAAC,aAAa,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAA;IAE/C,wEAAwE;IACxE,eAAe,EAAE,GAAG,CAAC,aAAa,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAA;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,SAAS,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,MAAM,GAAG,EACnF,WAAW,EAAE,EAAE,EACf,CAAC,EAAE,cAAc,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,UAAU;AACtC,UAAU,CAAC,EAAE,gBAAgB,CAAC,kBAAkB,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,EAC7E,OAAO,CAAC,EAAE,gBAAgB,CAAC,GAAG,EAAE,EAAE,CAAC,GA4LnB,sBAAsB,CAAC,GAAG,EAAE,EAAE,CAAC,CAChD"}

package/dist/openapi-mutation.js

@@ -1,72 +1,59 @@
-import { computed, ref, toValue } from 'vue';
+import { computed, ref } from 'vue';
 import { useMutation } from '@tanstack/vue-query';
 import { HttpMethod, } from './types.js';
-import { resolvePath, generateQueryKey, isPathResolved, getParamsOptionsFrom } from './openapi-utils.js';
+import { isPathResolved, normalizeParamsOptions, useResolvedOperation, resolvePath, generateQueryKey, } from './openapi-utils.js';
 /**
- * Composable for performing a strictly typed OpenAPI mutation operation using Vue Query.
- * Ensures the operation is a mutation (POST/PUT/PATCH/DELETE) at runtime.
- * Returns a reactive mutation object, including helpers for query key and enabled state.
+ * Execute a type-safe mutation (POST/PUT/PATCH/DELETE) with automatic cache updates.
  *
- * NOTE: By default, the mutation will automatically update cache with returned data and reload
- * any matching GET queries for the same path.
+ * Ensures the operation is a mutation at runtime and returns a reactive mutation object
+ * with helpers for path resolution and cache invalidation.
  *
- * @template T OperationId type representing the OpenAPI operation.
- * @param operationId The OpenAPI operation ID to mutate.
- * @param pathParams Optional path parameters for the endpoint, can be reactive.
- * @param options Optional mutation options, including Vue Query options and custom axios options:
- *   - 'dontUpdateCache': If true, will not update cache with returned data (default: false)
- *   - 'dontInvalidate': If true, will not invalidate matching GET queries (default: false)
- *  - 'invalidateOperations': List of additional OperationIds to invalidate after mutation (can also be a map of OperationId to path parameters)
- * - 'refetchEndpoints': List of additional EndpointQueryReturn objects to refetch after mutation
- *   - `axiosOptions`: Custom axios request options (e.g., headers, params)
- *   - All properties from {@link UseMutationOptions} (from @tanstack/vue-query)
- * @throws Error if the operation is not a mutation operation.
+ * NOTE: By default, the mutation updates cache for PUT/PATCH and invalidates matching
+ * GET queries for the same path.
+ *
+ * @template Ops - The operations type from your OpenAPI specification
+ * @template Op - The operation key from your operations type
+ * @param operationId - The OpenAPI operation ID to mutate
+ * @param h - OpenAPI helpers (internal), provided by useOpenApi
+ * @param pathParams - Path parameters (can be reactive). Omit for operations without path params.
+ * @param options - Mutation options (dontInvalidate, refetchEndpoints, etc.)
+ *   - `dontUpdateCache`: Skip cache update for PUT/PATCH responses
+ *   - `dontInvalidate`: Skip invalidating matching queries
+ *   - `invalidateOperations`: Additional operation IDs to invalidate (array or map of params)
+ *   - `refetchEndpoints`: Additional query results to refetch
+ *   - `queryParams`: Query string parameters (operation-specific)
+ *   - `axiosOptions`: Custom axios request options (headers, params, etc.)
+ *   - Plus all {@link UseMutationOptions} from @tanstack/vue-query
+ * @throws Error if the operation is not a mutation operation
  * @returns Mutation object with
- *   - `data`: ComputedRef of response data.
- *   - `isEnabled`: ComputedRef indicating if mutation can be executed (path resolved).
- *   - `extraPathParams`: Ref to set of additional path parameters when calling mutate.
- *   - `mutate` and `mutateAsync`: Functions to trigger the mutation, taking an object with:
- *     - `data`: The request body data for the mutation.
- *     - `pathParams`: Optional additional path parameters for the mutation.
- *     - `axiosOptions`: Optional axios configuration overrides for this specific mutation call.
- *    - `dontUpdateCache`, `dontInvalidate`, `invalidateOperations`, `refetchEndpoints`: Same as options, but can be set per-mutation.
- *   - All other properties and methods from the underlying Vue Query mutation object.
+ *   - `mutate(vars)` / `mutateAsync(vars)` to trigger the mutation
+ *   - `data`: ComputedRef of Axios response data
+ *   - `isEnabled`: ComputedRef indicating if mutation can execute (path resolved)
+ *   - `extraPathParams`: Ref to set additional path params at call time
+ *   - `pathParams`: Resolved path params as a computed ref
  */
 export function useEndpointMutation(operationId, h, // helpers
-pathParamsOrOptions, optionsOrNull) {
+pathParams, options) {
     // Runtime check to ensure this is actually a mutation operation
     if (!h.isMutationOperation(operationId)) {
-        throw new Error(`Operation ${String(operationId)} is not a mutation operation (POST/PUT/PATCH/DELETE)`);
+        const { method } = h.getOperationInfo(operationId);
+        throw new Error(`Operation '${String(operationId)}' uses method ${method} and cannot be used with useMutation(). ` +
+            `Use useQuery() for GET/HEAD/OPTIONS operations.`);
     }
     const { path, method } = h.getOperationInfo(operationId);
-    const { pathParams, options } = getParamsOptionsFrom(path, pathParamsOrOptions, optionsOrNull);
-    const { axiosOptions, dontInvalidate, dontUpdateCache, invalidateOperations, refetchEndpoints, queryParams, ...useMutationOptions } = options;
+    const { pathParams: resolvedPathParamsInput, options: resolvedOptions } = normalizeParamsOptions(pathParams, options);
+    const { axiosOptions, dontInvalidate, dontUpdateCache, invalidateOperations, refetchEndpoints, queryParams, ...useMutationOptions } = resolvedOptions;
     const extraPathParams = ref({});
-    // Compute the resolved path - same pattern as query
-    // This ensures that when pathParams is a function, it gets called within the computed
-    // so Vue can track dependencies of variables referenced inside the function
-    const basePathParams = computed(() => {
-        const result = toValue(pathParams);
-        return result;
-    });
-    const allPathParams = computed(() => ({
-        ...basePathParams.value,
-        ...extraPathParams.value,
-    }));
-    const resolvedPath = computed(() => resolvePath(path, allPathParams.value));
-    const queryKey = computed(() => generateQueryKey(resolvedPath.value));
-    // Make query parameters reactive
-    const allQueryParams = computed(() => {
-        const result = toValue(queryParams);
-        return result;
-    });
+    // Use the consolidated operation resolver with extraPathParams support
+    const { resolvedPath, queryKey, queryParams: resolvedQueryParams, pathParams: allPathParams, } = useResolvedOperation(path, resolvedPathParamsInput, queryParams, extraPathParams);
     const mutation = useMutation({
         mutationFn: async (vars) => {
             const { data, pathParams: pathParamsFromMutate, axiosOptions: axiosOptionsFromMutate, queryParams: queryParamsFromMutate, } = vars;
             extraPathParams.value = pathParamsFromMutate || {};
             // TODO: use typing to ensure all required path params are provided
             if (!isPathResolved(resolvedPath.value)) {
-                return Promise.reject(new Error(`Mutation for '${String(operationId)}' cannot be used, as path is not resolved: ${resolvedPath.value} (params: ${JSON.stringify(allPathParams.value)})`));
+                return Promise.reject(new Error(`Cannot execute mutation '${String(operationId)}': path parameters not resolved. ` +
+                    `Path: '${resolvedPath.value}', provided params: ${JSON.stringify(allPathParams.value)}`));
             }
             // Cancel any ongoing queries for this path (prevent race conditions with refresh)
             await h.queryClient.cancelQueries({ queryKey: queryKey.value, exact: false });
@@ -78,7 +65,7 @@ pathParamsOrOptions, optionsOrNull) {
                 ...axiosOptionsFromMutate,
                 params: {
                     ...(axiosOptions?.params || {}),
-                    ...(allQueryParams.value || {}),
+                    ...(resolvedQueryParams.value || {}),
                     ...(queryParamsFromMutate || {}),
                 },
             });
@@ -100,7 +87,7 @@ pathParamsOrOptions, optionsOrNull) {
                 await h.queryClient.invalidateQueries({ queryKey: queryKey.value, exact: method !== HttpMethod.POST });
                 const listPath = h.getListOperationPath(operationId);
                 if (listPath) {
-                    const listResolvedPath = resolvePath(listPath, pathParams);
+                    const listResolvedPath = resolvePath(listPath, resolvedPathParamsInput);
                     if (isPathResolved(listResolvedPath)) {
                         const listQueryKey = generateQueryKey(listResolvedPath);
                         // Invalidate list queries by comparing normalized query keys.