Feat: config based invalidation

[ScriptType]

Summary

This PR introduces configuration-based query invalidation support, initially implemented for angular-query. This allows developers to define cache invalidation rules directly in orval.config.ts rather than manually calling queryClient.invalidateQueries() in every component.

This is based on #2676 but without the optimistic update for now.

Usage

In your orval.config.ts, you can now specify mutationInvalidates within the query options:

export default defineConfig({
  petstore: {
    // ...
    output: {
      override: {
        query: {
          useInvalidate: true,
          signal: true,
          mutationInvalidates: [
            // Broad invalidation - invalidates all listPets queries
            {
              onMutations: ['createPets'],
              invalidates: ['listPets'],
            },
            // Targeted invalidation - invalidates specific pet by ID
            {
              onMutations: ['deletePet', 'updatePet', 'patchPet'],
              invalidates: [
                'listPets',
                { query: 'showPetById', params: ['petId'] },
              ],
            },
            {
              onMutations: ['uploadFile'],
              invalidates: ['listPets'],
            },
          ],
        },
      },
    },
  },
});

Invalidation Target Formats

Format	Description	Generated Code
'listPets'	Broad invalidation	getListPetsQueryKey()
{ query: 'showPetById', params: ['petId'] }	Same-name param mapping	getShowPetByIdQueryKey(variables.petId)
{ query: 'showPetById', params: { petId: 'id' } }	Explicit param mapping	getShowPetByIdQueryKey(variables.id)

Generated Code Example

For deletePet with the config above, orval generates:

const onSuccess = (data, variables, onMutateResult, context) => {
  queryClient.invalidateQueries({ queryKey: getListPetsQueryKey() });
  queryClient.invalidateQueries({ queryKey: getShowPetByIdQueryKey(variables.petId) });
  mutationOptions?.onSuccess?.(data, variables, onMutateResult, context);
};

Implementation Guide for Other Generators

The core types and normalization logic have been added to @orval/core, making this feature available for all generators to implement.

Types

// packages/core/src/types.ts
export type InvalidateTarget =
  | string
  | {
      query: string;
      params: string[] | Record<string, string>;
    };

export type MutationInvalidatesRule = {
  onMutations: string[];
  invalidates: InvalidateTarget[];
};

export type MutationInvalidatesConfig = MutationInvalidatesRule[];

Steps to Support in Other Clients

To support this in other clients (e.g., react-query, vue-query, svelte-query), generators need to:

1. Read the Config: Access mutationInvalidates from the query options object (available in NormalizedQueryOptions).

2. Filter Rules for Current Operation:

   const invalidatesConfig = (query.mutationInvalidates ?? [])
     .filter((rule) => rule.onMutations.includes(operationName))
     .flatMap((rule) => rule.invalidates);

3. Normalize and Deduplicate Targets:

   const normalizeTarget = (target) =>
     typeof target === 'string' ? { query: target } : target;

4. Generate Invalidation Code:

   • Inside the mutation's onSuccess callback, generate code to invalidate the target queries.
   • Use the existing query key generators (e.g., getListPetsQueryKey()) to ensure type safety.
   • For params, reference variables.<paramName> from the mutation.

Checklist

• Core config types added (InvalidateTarget, MutationInvalidatesRule)
• Logic implemented for angular-query
• Signal support enabled for all HTTP verbs (DELETE, PUT, PATCH)
• Params-based targeted invalidation support
• Sample app demonstrates all mutation types
• Comprehensive test coverage (15 tests)
• Tests passed

[melloware]

can you update the /docs too for this new configuration?

[ScriptType]

Sure, are there any other regards? Like stuff which you think could change? Or do you like the way?

[melloware]

Let's get some others to weigh in.

[AllieJonsson]

I think this is great!

[soartec-lab]

@ScriptType
It's a great idea, and I'm in favor of moving forward with it. However, I have one suggestion for improvement:

As written in the example, invalidating listPets depends on updating createPets, but the optional keys implicitly state the dependency.
Rather than assigning meaning to keys, make the keys explicitly descriptive and the values explicit.
Also, there may be multiple operations that can be disabled.

Taking this into consideration, how about doing it like this?

For example:

mutationInvalidates: [
  {
    invalidates: ['listPets', 'showPetById'],
    dependsOn: ['createPets', 'deletePet']
  },
  {
    invalidates: ['listPets'],
    dependsOn: ['createPets']
  },
]

[ScriptType]

@soartec-lab i agree, its a "bit" more complex to do it for the generation, but if we imagine when we have like 20 queries its much easier to maintain in the config.

[melloware]

ok i rebased your branch and its all working now

[melloware]

Build is all passing now!

[soartec-lab]

Looks good 👍