Query mutation options in core

.changeset/quiet-cooks-sparkle.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/query-core': minor
+---
+
+Add framework-agnostic `queryOptions` and `mutationOptions` helpers.

packages/angular-query-experimental/src/__tests__/mutation-options.test-d.ts

@@ -1,12 +1,16 @@
 import { assertType, describe, expectTypeOf, it } from 'vitest'
 import { queryKey } from '@tanstack/query-test-utils'
-import { QueryClient } from '@tanstack/query-core'
+import {
+  QueryClient,
+  mutationOptions as coreMutationOptions,
+} from '@tanstack/query-core'
 import {
   injectIsMutating,
   injectMutation,
   injectMutationState,
   mutationOptions,
 } from '..'
+import type { Signal } from '@angular/core'
 import type {
   DefaultError,
   MutationFunctionContext,
@@ -174,6 +178,20 @@ describe('mutationOptions', () => {
     )
   })
 
+  it('should infer types when core mutationOptions are used with injectMutation', () => {
+    const mutation = injectMutation(() =>
+      coreMutationOptions({
+        mutationFn: (input: { id: string }) => Promise.resolve(input.id),
+      }),
+    )
+
+    expectTypeOf(mutation.data).toEqualTypeOf<Signal<string | undefined>>()
+    expectTypeOf(mutation.variables).toEqualTypeOf<
+      Signal<{ id: string } | undefined>
+    >()
+    expectTypeOf(mutation.mutate).toBeCallableWith({ id: '1' })
+  })
+
   it('should infer types when used with injectIsMutating', () => {
     const key = queryKey()
     const isMutating = injectIsMutating(

packages/angular-query-experimental/src/__tests__/query-options.test-d.ts

@@ -2,6 +2,7 @@ import { assertType, describe, expectTypeOf, it } from 'vitest'
 import { queryKey } from '@tanstack/query-test-utils'
 import {
   QueryClient,
+  queryOptions as coreQueryOptions,
   dataTagSymbol,
   injectQuery,
   queryOptions,
@@ -69,6 +70,19 @@ it('should work when passed to injectQuery', () => {
   expectTypeOf(data).toEqualTypeOf<Signal<number | undefined>>()
 })
 
+it('should work when core queryOptions are passed to injectQuery', () => {
+  const key = queryKey()
+  const options = coreQueryOptions({
+    queryKey: key,
+    queryFn: () => Promise.resolve({ id: '1', title: 'Do Laundry' }),
+  })
+
+  const { data } = injectQuery(() => options)
+  expectTypeOf(data).toEqualTypeOf<
+    Signal<{ id: string; title: string } | undefined>
+  >()
+})
+
 it('should work when passed to fetchQuery', () => {
   const key = queryKey()
   const options = queryOptions({

packages/lit-query/src/tests/type-inference.test.ts

@@ -1,7 +1,9 @@
 import {
   dataTagErrorSymbol,
   dataTagSymbol,
+  mutationOptions as coreMutationOptions,
   QueryClient,
+  queryOptions as coreQueryOptions,
   type DefinedQueryObserverResult,
   type InfiniteData,
   type QueryObserverResult,
@@ -163,6 +165,18 @@ describe('type inference', () => {
       { id: number; name: string } | undefined
     >()
 
+    const coreQuery = createQueryController(
+      host,
+      () => coreQueryOptions({
+        queryKey: ['type-inference', 'core-query'] as const,
+        queryFn: async () => ({ id: '1', title: 'Do Laundry' }),
+      }),
+      client,
+    )
+    expectTypeOf(coreQuery().data).toEqualTypeOf<
+      { id: string; title: string } | undefined
+    >()
+
     const mutation = createMutationController(
       host,
       mutationOptions({
@@ -175,6 +189,18 @@ describe('type inference', () => {
       { id: number } | undefined
     >()
 
+    const coreMutation = createMutationController(
+      host,
+      () => coreMutationOptions({
+        mutationFn: async (input: { id: string }) => input.id,
+      }),
+      client,
+    )
+    expectTypeOf(coreMutation().data).toEqualTypeOf<string | undefined>()
+    expectTypeOf(coreMutation().variables).toEqualTypeOf<
+      { id: string } | undefined
+    >()
+
     const queryOpts = queryOptions({
       queryKey: ['type-inference', 'query-options'] as const,
       queryFn: async () => ({ id: 2, name: 'Grace' }),

packages/preact-query/src/__tests__/mutationOptions.test-d.tsx

@@ -1,4 +1,7 @@
-import { QueryClient } from '@tanstack/query-core'
+import {
+  QueryClient,
+  mutationOptions as coreMutationOptions,
+} from '@tanstack/query-core'
 import type {
   DefaultError,
   MutationFunctionContext,
@@ -162,6 +165,20 @@ describe('mutationOptions', () => {
     )
   })
 
+  it('should infer types when core mutationOptions are used with useMutation', () => {
+    const mutation = useMutation(
+      coreMutationOptions({
+        mutationFn: (input: { id: string }) => Promise.resolve(input.id),
+      }),
+    )
+
+    expectTypeOf(mutation.data).toEqualTypeOf<string | undefined>()
+    expectTypeOf(mutation.variables).toEqualTypeOf<
+      { id: string } | undefined
+    >()
+    expectTypeOf(mutation.mutate).toBeCallableWith({ id: '1' })
+  })
+
   it('should infer types when used with useIsMutating', () => {
     const isMutating = useIsMutating(
       mutationOptions({

packages/preact-query/src/__tests__/queryOptions.test-d.tsx

@@ -2,6 +2,7 @@ import {
   QueriesObserver,
   QueryClient,
   dataTagSymbol,
+  queryOptions as coreQueryOptions,
   skipToken,
 } from '@tanstack/query-core'
 import type {
@@ -55,6 +56,17 @@ describe('queryOptions', () => {
     const { data } = useQuery(options)
     expectTypeOf(data).toEqualTypeOf<number | undefined>()
   })
+  it('should work when core queryOptions are passed to useQuery', () => {
+    const options = coreQueryOptions({
+      queryKey: queryKey(),
+      queryFn: () => Promise.resolve({ id: '1', title: 'Do Laundry' }),
+    })
+
+    const { data } = useQuery(options)
+    expectTypeOf(data).toEqualTypeOf<
+      { id: string; title: string } | undefined
+    >()
+  })
   it('should work when passed to useSuspenseQuery', () => {
     const options = queryOptions({
       queryKey: queryKey(),

packages/query-core/src/__tests__/mutationOptions.test-d.tsx

@@ -0,0 +1,47 @@
+import { describe, expectTypeOf, it } from 'vitest'
+import { mutationOptions } from '../mutationOptions'
+import type { CoreMutationOptions } from '../index'
+
+describe('mutationOptions', () => {
+  it('should infer mutation data and variables', () => {
+    const options = mutationOptions({
+      mutationFn: (variables: { id: string }) => Promise.resolve(variables.id),
+      onSuccess: (data, variables) => {
+        expectTypeOf(data).toEqualTypeOf<string>()
+        expectTypeOf(variables).toEqualTypeOf<{ id: string }>()
+      },
+    })
+
+    expectTypeOf(options.mutationFn)
+      .parameter(0)
+      .toEqualTypeOf<{ id: string }>()
+    type MutationFn = NonNullable<typeof options.mutationFn>
+    expectTypeOf<Awaited<ReturnType<MutationFn>>>().toEqualTypeOf<string>()
+    expectTypeOf(options).not.toHaveProperty('mutationKey')
+  })
+
+  it('should preserve a required mutationKey', () => {
+    const options = mutationOptions({
+      mutationKey: ['key'],
+      mutationFn: (variables: { id: string }) => Promise.resolve(variables.id),
+    })
+
+    expectTypeOf(options.mutationKey).toEqualTypeOf<ReadonlyArray<unknown>>()
+  })
+
+  it('should export the reusable mutation options type', () => {
+    expectTypeOf<
+      CoreMutationOptions<string, Error, { id: string }>
+    >().toHaveProperty('mutationFn')
+  })
+
+  it('should not allow _defaulted', () => {
+    expectTypeOf(mutationOptions).parameter(0).not.toHaveProperty('_defaulted')
+
+    mutationOptions({
+      mutationFn: () => Promise.resolve(5),
+      // @ts-expect-error _defaulted is an internal option
+      _defaulted: true,
+    })
+  })
+})

packages/query-core/src/__tests__/queryOptions.test-d.tsx

@@ -0,0 +1,102 @@
+import { describe, expectTypeOf, it } from 'vitest'
+import { dataTagErrorSymbol, dataTagSymbol } from '../types'
+import { skipToken } from '../utils'
+import { QueryClient } from '../queryClient'
+import { queryOptions } from '../queryOptions'
+
+describe('queryOptions', () => {
+  it('should infer query data from queryFn', () => {
+    const options = queryOptions({
+      queryKey: ['key'],
+      queryFn: () => Promise.resolve(5),
+    })
+    type QueryFn = Exclude<typeof options.queryFn, typeof skipToken | undefined>
+
+    expectTypeOf<Awaited<ReturnType<QueryFn>>>().toEqualTypeOf<number>()
+    expectTypeOf(options.queryKey[dataTagSymbol]).toEqualTypeOf<number>()
+    expectTypeOf(options.queryKey[dataTagErrorSymbol]).toEqualTypeOf<Error>()
+  })
+
+  it('should tag queryKey with the query data type', () => {
+    const options = queryOptions({
+      queryKey: ['key'],
+      queryFn: () => Promise.resolve(5),
+    })
+    const queryClient = new QueryClient()
+    const data = queryClient.getQueryData(options.queryKey)
+
+    expectTypeOf(data).toEqualTypeOf<number | undefined>()
+  })
+
+  it('should type check values passed to setQueryData from the tagged queryKey', () => {
+    const options = queryOptions({
+      queryKey: ['todo'],
+      queryFn: () => Promise.resolve({ id: '1', title: 'Do Laundry' }),
+    })
+    const queryClient = new QueryClient()
+
+    queryClient.setQueryData(options.queryKey, {
+      id: '1',
+      title: 'Wash dishes',
+    })
+
+    queryClient.setQueryData(options.queryKey, (prev) => {
+      expectTypeOf(prev).toEqualTypeOf<
+        { id: string; title: string } | undefined
+      >()
+      return prev
+    })
+
+    // @ts-expect-error title should be a string
+    queryClient.setQueryData(options.queryKey, { id: '1', title: 1 })
+
+    // @ts-expect-error title is required
+    queryClient.setQueryData(options.queryKey, { id: '1' })
+  })
+
+  it('should allow initialData without a queryFn', () => {
+    const options = queryOptions({
+      queryKey: ['key'],
+      initialData: 1,
+    })
+    const queryClient = new QueryClient()
+    const data = queryClient.getQueryData(options.queryKey)
+
+    expectTypeOf(options.queryKey[dataTagSymbol]).toEqualTypeOf<number>()
+    expectTypeOf(data).toEqualTypeOf<number | undefined>()
+  })
+
+  it('should infer data when initialData is undefined', () => {
+    const options = queryOptions({
+      queryKey: ['key'],
+      queryFn: () => Promise.resolve(5),
+      initialData: undefined,
+    })
+
+    expectTypeOf(options.initialData).toEqualTypeOf<undefined>()
+    expectTypeOf(options.queryKey[dataTagSymbol]).toEqualTypeOf<number>()
+    expectTypeOf(options.queryKey[dataTagErrorSymbol]).toEqualTypeOf<Error>()
+  })
+
+  it('should infer a callable queryFn without skipToken', () => {
+    const options = queryOptions({
+      queryKey: ['key'],
+      queryFn: () => Promise.resolve(5),
+      enabled: false,
+    })
+    type QueryFn = Exclude<typeof options.queryFn, undefined>
+
+    expectTypeOf<QueryFn>().not.toEqualTypeOf<typeof skipToken>()
+    expectTypeOf<Awaited<ReturnType<QueryFn>>>().toEqualTypeOf<number>()
+    expectTypeOf(options.queryKey[dataTagSymbol]).toEqualTypeOf<number>()
+  })
+
+  it('should allow skipToken', () => {
+    const options = queryOptions({
+      queryKey: ['key'],
+      queryFn: skipToken,
+    })
+
+    expectTypeOf(options.queryKey[dataTagSymbol]).toEqualTypeOf<unknown>()
+  })
+})

packages/query-core/src/index.ts

@@ -42,6 +42,10 @@ export {
 export type { MutationFilters, QueryFilters, SkipToken, Updater } from './utils'
 
 export { streamedQuery as experimental_streamedQuery } from './streamedQuery'
+export { queryOptions } from './queryOptions'
+export type { CoreQueryOptions } from './queryOptions'
+export { mutationOptions } from './mutationOptions'
+export type { CoreMutationOptions } from './mutationOptions'
 
 // Types
 export type {

packages/query-core/src/mutationOptions.ts

@@ -0,0 +1,57 @@
+import type {
+  DefaultError,
+  MutationObserverOptions,
+  OmitKeyof,
+  WithRequired,
+} from './types'
+
+export type CoreMutationOptions<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TOnMutateResult = unknown,
+> = OmitKeyof<
+  MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>,
+  '_defaulted'
+>
+
+export function mutationOptions<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TOnMutateResult = unknown,
+>(
+  options: WithRequired<
+    CoreMutationOptions<TData, TError, TVariables, TOnMutateResult>,
+    'mutationKey'
+  >,
+): WithRequired<
+  CoreMutationOptions<TData, TError, TVariables, TOnMutateResult>,
+  'mutationKey'
+>
+
+export function mutationOptions<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TOnMutateResult = unknown,
+>(
+  options: Omit<
+    CoreMutationOptions<TData, TError, TVariables, TOnMutateResult>,
+    'mutationKey'
+  >,
+): Omit<
+  CoreMutationOptions<TData, TError, TVariables, TOnMutateResult>,
+  'mutationKey'
+>
+
+export function mutationOptions<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TOnMutateResult = unknown,
+>(
+  options: CoreMutationOptions<TData, TError, TVariables, TOnMutateResult>,
+): CoreMutationOptions<TData, TError, TVariables, TOnMutateResult> {
+  return options
+}