Prefix override for query keys/options factories

[farsil]

Description

When used with the react-query client, I would like an option in the orval configuration file to configure explicitly what prefix to use for factories.

Current behavior

If I use orval with react-query client, it internally determines whether to use a use or get prefix based on the presence of a custom query options factory:

  const queryOptionsFnName = camel(
    queryKeyMutator || queryOptionsMutator || mutator?.isHook
      ? `use-${name}-queryOptions`
      : `get-${name}-queryOptions`,
  );

However, the use prefix is sometimes undesirable for query options, since the function may have to be used outside react (router loaders for example, with ensureQueryData or prefetchQuery). You can use it anyway of course but:

1. It would be confusing in any react codebase
2. If you have certain eslint rules configured, you may have to disable the rule about React functions

Proposed behavior

Orval should let the user decide what prefix to use (if any) for query options factories, and possibly for query keys factories as well.

Proposed solution

The default automatic prefix could detect whether the mutators are hooks or not:

  const queryOptionsFnName = camel(
    queryKeyMutator?.isHook || queryOptionsMutator?.isHook || mutator?.isHook
      ? `use-${name}-queryOptions`
      : `get-${name}-queryOptions`,
  );

Moreover, we could introduce two new settings (queryKeyFactoryPrefix and queryOptionsFactoryPrefix, for example) that would live inside query. An empty prefix is sometimes desirable: my OpenAPI yaml files already prefix get operations with get, so with the default get prefix (assuming no mutators) it would result in a silly getGetActivitiesQueryOptions.

I am willing to put the work myself if you like the idea.

[melloware]

I feel like this is possible with one of the congfigs that is an override function and you write your own function to determine how you want it.

[melloware]

A PR is definitely welcome but I would research first that what you want is not already possible.

[melloware]

I think this is what you want:

https://orval.dev/docs/reference/configuration/output#querykey--queryoptions--mutationoptions

might have to look for tickets for examples. We should updaete the docs to show an example usage

[melloware]

@wadakatu do we have examples of this and mutationOptions overrides? It seems like the docs are sorely lacking here.

[wadakatu]

@melloware
Yes, we have examples in the test fixtures:

• queryOptions: PR fix(query): pass operationId and operationName to queryOptions mutator #3427 added both a configuration example (https://github.com/orval-labs/orval/blob/master/tests/configs/react-query.config.ts) and an operation-aware mutator
  (https://github.com/orval-labs/orval/blob/master/tests/mutators/custom-query-options-with-operation.ts).
• mutationOptions: we have a configuration example (https://github.com/orval-labs/orval/blob/master/tests/configs/react-query.config.ts) and a mutator example
  (https://github.com/orval-labs/orval/blob/master/tests/mutators/custom-mutation.ts) that invalidates a query based on the operation ID. This was originally introduced in fix(query): bugfix for custom mutator options #1974.

I agree that the current documentation is too brief. We could use these fixtures as the basis for complete configuration and mutator examples.

However, I checked the current naming implementation, and these overrides do not provide independent control over the generated factory function prefix. The name in a mutator configuration selects the custom function that Orval imports and calls; it does not set the name of the generated factory.

In fact, the presence of a queryKey or queryOptions mutator currently causes the generated query-options factory to use the use prefix, even when the mutator itself is not a hook. mutationOptions behaves similarly.

An operationName override could indirectly change the operation-derived part of the generated names, but it would also affect the other symbols generated for that operation. It cannot customize only the query key/options factory prefix.

Therefore, I don’t think the existing queryKey / queryOptions / mutationOptions overrides fully address the request in #3790. The proposed isHook check would fix the misleading use prefix for non-hook mutators, while a separate prefix option would still be needed to support an arbitrary or empty prefix.

[melloware]

thank you for your analysis @wadakatu !