refactor(query-core): change QueryMeta and MutationMeta to accept generic types

[vojvodics]

Referring to #4253 and https://tkdodo.eu/blog/breaking-react-querys-api-on-purpose.

Assuming I have a setup like this:

interface MyMeta {
  errorMessage: string | ((error: unknown, variables: unknown, context: unknown) => string);
}

declare module '@tanstack/react-query' {
  interface QueryMeta extends MyMeta {}
}

const queryClient = new QueryClient({
  mutationCache: new MutationCache({
    onError: (error, variables, context, mutation) => {
      if (query.meta.errorMessage) {
		const message = 
			typeof query.meta.errorMessage === 'function' 
				? query.meta.errorMessage(error, variables, context) 
				: query.meta.errorMessage;
        toast.error(message)
      }
    },
  }),
})

export function useDeleteTodo() {
  return useMutation({
    mutationFn: deleteTodo,
    meta: {
	  // I have to specify the type
      errorMessage: (_error, todo: Todo) => `Failed to delete ${todo.name}`
    },
  })
}

This PR enables you to infer the types correctly in meta field:

interface MyMeta<
  TData = unknown,
  TError = unknown,
  TVariables = void,
  TContext = unknown
> {
  errorMessage: string | ((error: TError, variables: TVariables, context: TContext) => string);
  // I can also infer the type of data correctly
  successMessage: string | ((data: TData, variables: TVariables, context: TContext) => string);
}

declare module '@tanstack/react-query' {
  interface QueryMeta<
    TData = unknown,
    TError = unknown,
    TVariables = void,
    TContext = unknown
  > extends MyMeta<TData, TError, TVariables, TContext> {}
}

const queryClient = new QueryClient({
  mutationCache: new MutationCache({
    onError: (error, variables, context, mutation) => {
      if (query.meta.errorMessage) {
		const message = 
			typeof query.meta.errorMessage === 'function' 
				? query.meta.errorMessage(error, variables, context) 
				: query.meta.errorMessage;
        toast.error(message)
      }
    },
  }),
})

export function useDeleteTodo() {
  return useMutation({
    mutationFn: deleteTodo,
    meta: {
	  // todo is inferred correctly now
      errorMessage: (_error, todo) => `Failed to delete ${todo.name}`
    },
  })
}

Besides inference this will catch type errors when refactoring - if we want to refactor deleteTodo from function deleteTodo(todo: Todo): Promise<void> to function deleteTodo(options: {todo: Todo, projectId: string}): Promise<void>, we'll get a type error, however, without inference we could easily miss this.

Is there any way to ignore the errors of unused types?
Is there a docs section that I should update?

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

1 Ignored Deployment

Name	Status	Preview	Comments	Updated (UTC)
query	⬜️ Ignored (Inspect)			May 16, 2023 9:24am

[TkDodo]

please have a look at how we solved this differently in v5:

https://tanstack.com/query/v5/docs/react/typescript#registering-a-global-error

I realise the docs are for error only, but we have the same thing for meta:

query/packages/query-core/src/types.ts

Lines 11 to 15 in b657107

	export interface Register {
	// defaultError: Error
	// queryMeta: Record<string, unknown>
	// mutationMeta: Record<string, unknown>
	}

[vojvodics]

Interesting... Although I still don't see how that implementation will help me infer types in meta functions 😕

In v5 I'd override it like this:

interface MyMeta {
  errorMessage: string | ((error: unknown, variables: unknown, context: unknown) => string);
}

declare module '@tanstack/react-query' {
  interface Register {
    mutationMeta: MyMeta;
  }
}

But I still won't be able to infer the values, so I think the Register needs to be generic (for this to work):

interface MyMeta<
  TData = unknown,
  TError = unknown,
  TVariables = void,
  TContext = unknown
> {
  errorMessage: string | ((error: TError, variables: TVariables, context: TContext) => string);
  // I can also infer the type of data correctly
  successMessage: string | ((data: TData, variables: TVariables, context: TContext) => string);
}

declare module '@tanstack/react-query' {
  interface Register<
    TData = unknown,
    TError = unknown,
    TVariables = void,
    TContext = unknown
  > {
    mutationMeta: MyMeta<TData, TError, TVariables, TContext>;
  }
}

I can create a PR for the v5 branch if you'd like this to be a v5 feature only

I can also create a reproduction repo if it helps to highlight the problem this solves

[TkDodo]

meta is available in situations where you can't really determine what type it is, e.g. when iterating over all Queries. For example:

queryClient.invaliadateQueries({ predicate: query => ... })

here, query.meta cannot be inferred to anything specific I think. We also don't infer query.queryKey here.

but I can see that the function use-case is pretty interesting. If you can make a PR for v5 (alpha branch), I can take another look!

[bryanltobing]

i try to solve it using declaration merging but this doesn't seem to work

declare module '@tanstack/react-query' {
  interface MutationMeta {
    customField1: string;
    customField2: number;
  }
}

// mutation.meta?.customField1 <- doesn't type safe

updates: nevermind, it does work