fix(query): namespace non-GET query keys with the HTTP verb (orval-labs#3312)

* fix(query): namespace non-GET query keys with the HTTP verb

When a non-GET operation is routed to a Query hook (today only via
operation-level `query.useQuery: true`, and the upcoming fix for orval-labs#2376),
its generated cache key was path-only — e.g. both `GET /pets` and
`POST /pets` produced keys starting with `'/pets'`. TanStack Query then
mixed their cached data and
`invalidateQueries({ queryKey: ['/pets'] })` matched both, which is a
silent runtime bug (no type error, no snapshot diff).

Insert the uppercased HTTP verb as a leading segment when:
- `verb !== GET`, AND
- `useOperationIdAsQueryKey` is not enabled (operation IDs are already
  unique across verb + path, so the prefix would be redundant).

Existing GET keys and operation-id-based keys are unchanged.

This unblocks orval-labs#2376 by making it safe for the eventual fix to globally
route non-GET operations to Query hooks without cache key collisions.

BREAKING CHANGE: Users that already opt non-GET operations into Query
hooks via `override.operations.<id>.query.useQuery: true` will see their
cache keys gain a leading verb segment (e.g. `['/pets', body]` →
`['POST', '/pets', body]`). Update any `invalidateQueries` /
`getQueryData` calls that filter by these keys.

* fix(query): keep broad invalidation working for verb-prefixed cache keys

Address Copilot review on orval-labs#3312: when a non-GET operation is routed to
a Query hook and a `mutationInvalidates` rule targets it without
providing the required path params, the broad-invalidation fallback
emitted a predicate / partial key that no longer matched the cache
key (because the cache key now starts with the verb segment).

Mirror `getQueryKeyVerbPrefix`'s behavior in `mutation-generator.ts`:

- Default mode: predicate becomes
  `query.queryKey[0] === 'DELETE' && query.queryKey[1].startsWith('/pets/')`.
- Split-key mode: partial key becomes `['DELETE', 'pets']`.

Verb prefix is suppressed for GET targets (existing behavior preserved)
and when `useOperationIdAsQueryKey` is enabled (operation IDs are
already verb+path unique, so `getQueryKeyVerbPrefix` does not insert a
prefix and neither should the invalidation logic).

Also extends the `getQueryKeyVerbPrefix` unit tests to cover HEAD per
Copilot feedback, so all `Verbs` enum members are exercised.

Two new snapshot configs document the fixed behavior:
- `invalidatesNonGetQueryTarget` — default mode.
- `invalidatesNonGetQueryTargetSplitKey` — split-key mode.

* refactor(query): reuse getQueryKeyVerbPrefix in mutation-generator

Address CodeRabbit nitpick on orval-labs#3312: the verb prefix logic in
`createGenerateInvalidateCall` duplicated the rules in
`getQueryKeyVerbPrefix`. Importing the helper directly removes that
duplication so the two sites stay in sync if the prefix rules ever
change.

`info.method` is widened by the spec walker to HTTP_METHODS (a superset
of `Verbs` that also includes `options`/`trace`), but the helper only
branches on `Verbs.GET`, so casting is safe — any non-GET method is
treated identically.

Author: wadakatu

packages/query/src/mutation-generator.ts

@@ -11,6 +11,7 @@ import {
   isString,
   type OutputHttpClient,
   pascal,
+  type Verbs,
 } from '@orval/core';
 
 import {
@@ -19,6 +20,7 @@ import {
   getQueryErrorType,
 } from './client';
 import type { FrameworkAdapter } from './framework-adapter';
+import { getQueryKeyVerbPrefix } from './query-generator';
 import { getQueryOptionsDefinition } from './query-options';
 
 interface NormalizedTarget {
@@ -62,6 +64,9 @@ const HTTP_METHODS = [
 
 interface OperationRouteInfo {
   route: string;
+  /** HTTP method (lowercase) — needed to mirror the verb prefix that
+   * `getQueryKeyVerbPrefix` adds to non-GET cache keys. */
+  method: string;
   /** true when the route has path params that lack a default value */
   hasRequiredPathParams: boolean;
 }
@@ -108,7 +113,7 @@ const findOperationInfo = (
       if (opId !== operationName && camel(opId) !== operationName) continue;
 
       if (!routePath.includes('{')) {
-        return { route: routePath, hasRequiredPathParams: false };
+        return { route: routePath, method, hasRequiredPathParams: false };
       }
 
       // Collect path parameters from both path-level and operation-level
@@ -121,7 +126,7 @@ const findOperationInfo = (
         (p) => p.schema?.default === undefined && p.default === undefined,
       );
 
-      return { route: routePath, hasRequiredPathParams };
+      return { route: routePath, method, hasRequiredPathParams };
     }
   }
   return undefined;
@@ -204,6 +209,7 @@ const generateParamArgs = (
 const createGenerateInvalidateCall = (
   spec: Record<string, unknown> | undefined,
   shouldSplitQueryKey: boolean,
+  useOperationIdAsQueryKey: boolean,
 ) => {
   return (target: NormalizedTarget): string => {
     const method =
@@ -228,19 +234,42 @@ const createGenerateInvalidateCall = (
       // starts with a path param like /{tenantId}/...), fall through to
       // the zero-arg call rather than generating an overly-broad match.
       if (prefix !== undefined) {
+        // Mirror the verb prefix that `getQueryKeyVerbPrefix` injects into
+        // non-GET Query keys; without this, the predicate / partial key
+        // would never match a verb-prefixed cache key and the broad
+        // invalidation would silently no-op. We share the helper from
+        // `query-generator.ts` so both sites stay in sync.
+        // `info.method` is narrowed by the spec walker to one of HTTP_METHODS
+        // (a superset of `Verbs` that also includes `options`/`trace`); the
+        // helper only branches on `Verbs.GET`, so the cast is safe for any
+        // non-GET method.
+        const verbPrefix = getQueryKeyVerbPrefix({
+          verb: info.method as Verbs,
+          useOperationIdAsQueryKey,
+        });
+
         if (shouldSplitQueryKey) {
-          // Split-key mode: query keys are arrays like ['pets', petId].
+          // Split-key mode: query keys are arrays like ['pets', petId]
+          // (or ['DELETE', 'pets', petId] for non-GET Query keys).
           // Use partial key matching with static route segments.
           const segments = prefix
             .split('/')
             .filter((s) => s !== '')
             .map((s) => `'${s}'`)
             .join(', ');
-          return `    queryClient.${method}({ queryKey: [${segments}] });`;
+          const keyArr = verbPrefix
+            ? `['${verbPrefix}', ${segments}]`
+            : `[${segments}]`;
+          return `    queryClient.${method}({ queryKey: ${keyArr} });`;
         }
 
-        // Default mode: query keys are template strings like ['/pets/${petId}'].
-        // Use predicate with startsWith for broad matching.
+        // Default mode: query keys are template strings like
+        // ['/pets/${petId}'] (or ['DELETE', '/pets/${petId}'] for non-GET
+        // Query keys). Use a predicate that knows where the route segment
+        // lives in the tuple.
+        if (verbPrefix) {
+          return `    queryClient.${method}({ predicate: (query) => query.queryKey[0] === '${verbPrefix}' && typeof query.queryKey[1] === 'string' && query.queryKey[1].startsWith('${prefix}') });`;
+        }
         return `    queryClient.${method}({ predicate: (query) => typeof query.queryKey[0] === 'string' && query.queryKey[0].startsWith('${prefix}') });`;
       }
     }
@@ -422,6 +451,7 @@ ${
         generateInvalidateCall: createGenerateInvalidateCall(
           context.spec,
           !!query.shouldSplitQueryKey,
+          !!query.useOperationIdAsQueryKey,
         ),
         uniqueInvalidates,
       })

packages/query/src/query-generator.test.ts

@@ -1,6 +1,10 @@
+import { Verbs } from '@orval/core';
 import { describe, expect, it } from 'vitest';
 
-import { getMutationInvalidatesConflictWarning } from './query-generator';
+import {
+  getMutationInvalidatesConflictWarning,
+  getQueryKeyVerbPrefix,
+} from './query-generator';
 
 const ruleFor = (op: string) => ({
   onMutations: [op],
@@ -103,3 +107,65 @@ describe('getMutationInvalidatesConflictWarning', () => {
     expect(message).toContain("'createPets'");
   });
 });
+
+describe('getQueryKeyVerbPrefix', () => {
+  it('returns undefined for GET so existing GET keys remain unchanged', () => {
+    expect(
+      getQueryKeyVerbPrefix({
+        verb: Verbs.GET,
+        useOperationIdAsQueryKey: false,
+      }),
+    ).toBeUndefined();
+  });
+
+  it('returns the uppercased verb for non-GET verbs to disambiguate cache keys', () => {
+    expect(
+      getQueryKeyVerbPrefix({
+        verb: Verbs.POST,
+        useOperationIdAsQueryKey: false,
+      }),
+    ).toBe('POST');
+    expect(
+      getQueryKeyVerbPrefix({
+        verb: Verbs.PUT,
+        useOperationIdAsQueryKey: false,
+      }),
+    ).toBe('PUT');
+    expect(
+      getQueryKeyVerbPrefix({
+        verb: Verbs.PATCH,
+        useOperationIdAsQueryKey: false,
+      }),
+    ).toBe('PATCH');
+    expect(
+      getQueryKeyVerbPrefix({
+        verb: Verbs.DELETE,
+        useOperationIdAsQueryKey: false,
+      }),
+    ).toBe('DELETE');
+    expect(
+      getQueryKeyVerbPrefix({
+        verb: Verbs.HEAD,
+        useOperationIdAsQueryKey: false,
+      }),
+    ).toBe('HEAD');
+  });
+
+  it('returns undefined when useOperationIdAsQueryKey is true (operation IDs are already verb+path unique)', () => {
+    expect(
+      getQueryKeyVerbPrefix({
+        verb: Verbs.POST,
+        useOperationIdAsQueryKey: true,
+      }),
+    ).toBeUndefined();
+  });
+
+  it('treats undefined useOperationIdAsQueryKey as falsy', () => {
+    expect(
+      getQueryKeyVerbPrefix({
+        verb: Verbs.POST,
+        useOperationIdAsQueryKey: undefined,
+      }),
+    ).toBe('POST');
+  });
+});

packages/query/src/query-generator.ts

@@ -74,6 +74,32 @@ export const getMutationInvalidatesConflictWarning = ({
   );
 };
 
+/**
+ * Computes a verb prefix segment for query keys when a non-GET operation is
+ * routed to a Query hook. Without this prefix, two operations sharing a path
+ * (e.g. `GET /pets` and `POST /pets`) would generate cache keys that both
+ * begin with `'/pets'`, so TanStack Query would mix their cached data and
+ * `invalidateQueries({ queryKey: ['/pets'] })` would match both.
+ *
+ * Skipped for GET (preserves existing keys) and when
+ * `useOperationIdAsQueryKey` is enabled (operation IDs are already unique
+ * across verb + path, so the prefix would be redundant).
+ *
+ * Returns the uppercased verb when a prefix should be inserted, or
+ * `undefined` when no prefix is needed.
+ */
+export const getQueryKeyVerbPrefix = ({
+  verb,
+  useOperationIdAsQueryKey,
+}: {
+  verb: Verbs;
+  useOperationIdAsQueryKey: boolean | undefined;
+}): string | undefined => {
+  if (useOperationIdAsQueryKey) return undefined;
+  if (verb === Verbs.GET) return undefined;
+  return verb.toUpperCase();
+};
+
 const getQueryFnArguments = ({
   hasQueryParam,
   hasSignal,
@@ -887,6 +913,11 @@ export const generateQueryHook = async (
           .map((p) => `...(${p.name} ? [${p.name}] : [])`)
           .join(', ');
 
+        const verbPrefix = getQueryKeyVerbPrefix({
+          verb,
+          useOperationIdAsQueryKey: override.query.useOperationIdAsQueryKey,
+        });
+
         // Note: do not unref() params in Vue - this will make key lose reactivity
         queryKeyFns += `
 ${override.query.shouldExportQueryKey ? 'export ' : ''}const ${queryOption.queryKeyFnName} = (${queryKeyProps}) => {
@@ -896,6 +927,7 @@ ${override.query.shouldExportQueryKey ? 'export ' : ''}const ${queryOption.query
       queryOption.type === QueryType.SUSPENSE_INFINITE
         ? `'infinite'`
         : '',
+      verbPrefix ? `'${verbPrefix}'` : '',
       queryKeyIdentifier,
       queryKeyParams,
       body.implementation,