Add mutationOptions (parity with TanStack Query)

[minchodang]

Description

openapi-react-query provides ergonomic helpers for queries (e.g., queryOptions), but there’s no equivalent for mutations. Even if mutation demand is lower in some codebases, a first-class mutationOptions would:
• Enable reuse of a shared mutationFn, lifecycle handlers, retry policies, and meta across many components.
• Standardize key composition and invalidation behavior in the same way queries do (no ad-hoc keys).
• Reduce boilerplate in tests/stories and improve DX while preserving endpoint-aware typing.

This feature targets parity of ergonomics with TanStack Query’s concept of mutationOptions, while keeping the API and key semantics consistent with this library’s existing query helpers.

Proposal

Introduce and export a mutationOptions helper that mirrors the style of existing query helpers in this package (not a new factory shape), and preserves the library’s key strategy.

API shape (aligned with existing helpers)
• Accept method and path, inferring types from generated OpenAPI definitions.
• Accept an options bag for lifecycle callbacks (onSuccess, onError, onSettled), retry/backoff, meta, etc.
• Allow the endpoint mutationFn to be provided either:
• up front (pre-bound at creation), or
• at the use site (same flexibility as query helpers).

Key semantics
• Compute mutationKey using the same internal key composer as queries to keep structure stable and familiar.
• Do not introduce a new key scheme; maintain compatibility with existing invalidation recipes.

Illustrative usage

import { mutationOptions } from '@openapi-ts/openapi-react-query';
import { queryClient } from './queryClient';

// Pre-bound, endpoint-aware bundle with the same key composition as queries
export const updateUser = mutationOptions('PUT', '/users/{id}', {
  mutationFn: ({ id, body }) =>
    client.PUT('/users/{id}', { params: { path: { id } }, body }),
  onSuccess: (_data, { id }) => {
    queryClient.invalidateQueries({ queryKey: ['users', { id }] });
  },
  retry: 1,
});

// In a component
const mutation = useMutation(updateUser);

Typing
• Preserve inference for TData, TError, and variables derived from the OpenAPI path/body schemas, matching the behavior of existing query helpers.

Backwards compatibility
• Purely additive; no behavior changes for existing code or key composition.

Tests & docs
• Type tests (tsd) for correct inference from generated paths/methods.
• Runtime tests covering key composition parity and lifecycle callbacks.
• Documentation mirroring query-helper pages, plus an OpenAPI-bound example and a short note on reuse patterns for mutations.
• Reference TanStack’s mutationOptions docs for conceptual parity.

Extra

• I’m willing to open a PR (see CONTRIBUTING.md)