Can we add createMutationOptions()?

[Rendez]

https://tanstack.com/query/latest/docs/framework/react/reference/mutationOptions

Should I open a PR?

[paul-sachs]

What exactly are we trying to achieve by exposing these options? useMutation is a very tiny wrapper around callUnaryMethod. I hesitate to add API surface unless there's a large enough benefit so I want to understand what it might add.

[Rendez]

Let me have a deeper look, I posted this quite hastily I must admit. I found myself using createQueryOptions a lot today and didn't have time to play with mutations yet. I'm trying to centralize all mutations also in the same file where I create all query options in advance, because of our heavy usage of tanstack-router's context feature to pass these objects down to the use* tanstack-query hooks

[Rendez]

Hey @paul-sachs, multiple issues on this thread, excuse its length.

First off, I came up with something that works for our particular approach. I am not sure if we want to include anything like this in connect-query-es. I believe createQueryOptions for instance was already a stretch, am I right? The reason being you can't predict which options the user wants to provide, but you definitely wanted to solve structuralSharing, queryKey and queryFn to facilitate most use-cases.

We share that sentiment, and I think the choice for createQueryOptions was mostly correct. For a potential createMutationOptions (TanStack/query#8960) one has to be much more opinionated. This is what we're aiming for (I'll drop the create* prefix as we prefer it):

1. Prepare queryOptions and mutationOptions as much as possible in our tanstack-router Routes (via context/beforeLoad). Specifying these memoizes them, and prevents the same definition twice in the code base. It also prevents the use of useSearch() from tanstack-router all across our components
2. For the majority of our cases the input for queryOptions is very much known in advanced in Routes, thanks to URL params and search
3. For some cases the input for mutationOptions is known or partly available in Routes, for the same reasons
4. onSuccess, onSettled, onError definitions should live closer to the useMutation hook, not in Routes because there's a level of detachment we do not like, as these handle side-effects in components, and are less related to routes, so we exclude these options from mutationOptions
5. contextValues are very much necessary in our case, but the current impl. does not allow to pass any.
6. UseQueryOptions as exported can't be used for argument typing to pass queryOptions around our components, so we had to reimplement the type. It would be nice if it could be exported:
   With the exported UseQueryOptions we have issues with the inferred data returned...

For:

async function resolve(myQueryOptions:UseQueryOptions<typeof ...Schema>
const x = await queryClient.fetchQuery(myQueryOptions)

We should be getting:

const x = {
    readonly $typeName: "...Response";
    $unknown?: UnknownField[];
    someOtherField: string;
}

But instead we get (sorry it's contextified):

Note: on this point, I'm actively working to see if it's an just "our" issue.

---

Anyways, our version of queryOptions and mutationOptions. Feedback very much welcome:

import {
  DescMessage,
  DescMethod,
  DescService,
  Message,
  MessageShape,
  MessageInitShape,
  DescMethodUnary,
  create,
  equals,
  isMessage,
} from '@bufbuild/protobuf';
import { GenMessage } from '@bufbuild/protobuf/codegenv2';
import { ConnectError, ContextValues, createContextKey, Transport } from '@connectrpc/connect';
import { ConnectQueryKey, createConnectQueryKey } from '@connectrpc/connect-query';
import { createConnectTransport } from '@connectrpc/connect-web';
import {
  UseQueryOptions as UseQueryOptionsReactQuery,
  UseMutationOptions as UseMutationOptionsReactQuery,
  replaceEqualDeep,
  QueryFunctionContext,
  QueryKey,
  QueryMeta,
} from '@tanstack/react-query';
import {
  connectQueryApiClientErrorMiddleware,
  connectQueryAuthMiddleware,
  connectQueryVersionHeaderMiddleware,
} from '@/api/middlewares';

/**
 * ConnectRPC integration utilities for TanStack Query compatibility.
 *
 * @see {@link https://connectrpc.com/docs/web/getting-started} ConnectRPC Documentation
 * @see {@link https://tanstack.com/query/latest} TanStack Query Documentation
 */
export const transport = createConnectTransport({
  baseUrl: '/connect',
  interceptors: [connectQueryAuthMiddleware, connectQueryVersionHeaderMiddleware, connectQueryApiClientErrorMiddleware],
});

export type UseQueryOptions<O extends DescMessage, SelectOutData = MessageShape<O>> = UseQueryOptionsReactQuery<
  MessageShape<O>,
  ConnectError,
  SelectOutData,
  ConnectQueryKey<O>
>;

export type UseMutationOptions<
  O extends DescMessage,
  I extends DescMessage,
  TContext = unknown,
> = UseMutationOptionsReactQuery<MessageShape<O>, ConnectError, MessageInput<MessageShape<I>>, TContext>;

export type MessageInput<T extends Message> = Omit<MessageInit<T>, '$typeName'>;

export type MessageOutput<T extends Message> = GenMessage<T>;

type MessageInit<T extends Message> = {
  [K in keyof T as K extends `$unknown` ? never : K]: K extends '$typeName' ? never : T[K];
};

export const ctxKeyAuthorized = createContextKey<boolean>(true, {
  description: 'No authorization required',
});

/**
 * Creates the most appropriate options required to make a mutation.
 */
export function mutationOptions<
  O extends DescMessage,
  I extends DescMessage,
  TInput extends MessageInitShape<I>,
  TVariables extends MessageInput<MessageShape<I>>,
  TOptions extends UseMutationOptions<O, I>,
>(
  schema: DescMethodUnary<I, O>,
  input: TInput | void,
  {
    transport,
    contextValues,
    ...options
  }: Omit<
    TOptions,
    | 'mutationKey'
    | 'mutationFn'
    | `on${string extends infer S extends string ? (S extends Uppercase<S> ? Uppercase<S> : '') : ''}${string}`
  > & {
    transport: Transport;
    /**
     * Additional context values to pass to the transport.
     * @see https://connectrpc.com/docs/web/interceptors#context-values
     */
    contextValues?: ContextValues;
  },
) {
  const body = input ?? create(schema.input);
  return {
    mutationKey: createConnectQueryKey({
      schema,
      input: body,
      transport,
      cardinality: 'finite',
    }),
    mutationFn: (variables: Partial<TVariables> | void) =>
      callUnaryMethod(transport, schema, { ...body, ...variables }, { contextValues }),
    ...options,
  };
}

// Copyright 2021-2023 The Connect Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

/**
 * Creates the most appropriate options required to make a query.
 */
export function queryOptions<I extends DescMessage, O extends DescMessage>(
  schema: DescMethodUnary<I, O>,
  input: MessageInitShape<I> | undefined,
  {
    transport,
    contextValues,
  }: {
    transport: Transport;
    contextValues?: ContextValues;
  },
) {
  const queryKey = createConnectQueryKey({
    schema,
    input: input ?? create(schema.input),
    transport,
    cardinality: 'finite',
  });
  const structuralSharing = createStructuralSharing(schema.output);
  const queryFn = createUnaryQueryFn(transport, schema, input, contextValues);
  return { queryKey, queryFn, structuralSharing };
}

/**
 * Returns a simplistic implementation for "structural sharing" for a Protobuf
 * message.
 *
 * To keep references intact between re-renders, we return the old version if it
 * equals the new version.
 *
 * @see https://tanstack.com/query/latest/docs/framework/react/guides/render-optimizations#structural-sharing
 */
function createStructuralSharing(schema: DescMessage) {
  return function structuralSharing(oldData: unknown, newData: unknown): unknown {
    if (!isMessage(oldData) || !isMessage(newData)) {
      return replaceEqualDeep(oldData, newData);
    }
    if (!equals(schema, oldData, newData)) {
      return newData;
    }
    return oldData;
  };
}

/**
 * Creates a unary query function.
 */
function createUnaryQueryFn<
  I extends DescMessage,
  O extends DescMessage,
  TQueryKey extends QueryKey = QueryKey,
  TPageParam = never,
>(
  transport: Transport,
  schema: DescMethodUnary<I, O>,
  input: MessageInitShape<I> | undefined,
  contextValues?: ContextValues,
) {
  return (context: QueryFunctionContext<TQueryKey, TPageParam> | void) => {
    return callUnaryMethod(transport, schema, input, {
      signal: context?.signal,
      contextValues,
    });
  };
}

/**
 * Call a unary method given its signature and input.
 */
async function callUnaryMethod<I extends DescMessage, O extends DescMessage>(
  transport: Transport,
  schema: DescMethodUnary<I, O>,
  input: MessageInitShape<I> | undefined,
  options?: {
    signal?: AbortSignal;
    contextValues?: ContextValues;
  },
): Promise<MessageShape<O>> {
  const result = await transport.unary(
    schema,
    options?.signal,
    undefined, // timeoutMs
    undefined, // header
    input ?? create(schema.input),
    options?.contextValues,
  );
  return result.message;
}

[paul-sachs]

So if i understand this correctly, your setup is as follows:

1. On route handling, configure some default options that are passed via props to nested components
2. Nested components can use options to call useQuery or useMutation to gather data that was prefetched and add callback methods for mutations

That setup could work, though to me it feels like prop drilling would present some flexibility challenges but that's a personal preference.

Either way, what you've laid out here will require i think two distinct issues that we should probably split out into their own concerns:

1. Allow contextValues. This has been raised before (in Ability to pass CallOptions #516). This has presented some reactivity challenges so perhaps only allowing it direct create*Options calls would alleviate that concern.
2. Export a type helper to represent the return value of create*Options methods since the current UseQueryOptions type is actually just a representation of the options that can be passed INTO useQuery.

Does that about sum it up?

[Rendez]

That setup could work, though to me it feels like prop drilling would present some flexibility challenges but that's a personal preference.

If you were referring to the default options object being passed around, we're either leveraging getRouteApi('...').useRouteContext() to avoid prop drilling where appropriate or if these are conditional (sometimes we return null in beforeLoad() due to some heuristics), we use it to conditionally render a component that internally will do useSuspenseQuery(), so it's normally just one pass via props and not many.

Allow contextValues. This has been raised before [...]

I initially look at the option meta, and thought about the relation with contextValues, and I know this one is meant for interceptors, but passing meta around as a contextValue could perhaps be a good pattern, I am not sure.

The only usage of meta for us is to pass around a boolean flag that determines whether we add an Authorization header to the request, because we do not want to have an allow-list of service+methods, and instead would like meta to carry this. Since we're switching to interceptors from our OpenAPI client's middleware, which passed around meta, we thought it might work.

Export a type helper to represent the return value of create*Options methods since the current UseQueryOptions type is actually just a representation of the options that can be passed INTO useQuery.

Yes, please.

Does that about sum it up?

Very well Sir.

[paul-sachs]

Ah yes, I was reading about how tanstack/router does typesafe context, that would indeed limit the prop drilling. Neat.

Regarding the contextValues, will those be needed in a useQuery or useSuspenseQuery calls or are they just being called with queryClient APIs? We've yet to solve the reactivity problems with those solution so I'm curious how you're handling passing contextValues into useQuery.

[paul-sachs]

So we've released at least part of the request here with v2.2.0. Now we support headers and export the types (see docs). contextValues is a little more complicated. Adding it for mutations alone is pretty easy but it does feel like it would be weird to support it only on mutations. And queries then need to take in contextValues into the key, which is where things get a little more complicated.