refactor!: rename type 'UseQueryKey' to 'UseEntryKey'

BREAKING CHANGE: the exported type 'UseQueryKey' is replaced by the more generic type 'UseEntryKey', which will be also used to type mutations

playground/src/pages/ecom/item/[id].vue

@@ -25,6 +25,7 @@ const itemAvailability = ref()
 watch(() => item.value?.availability, (value) => itemAvailability.value = value)
 
 const { mutate: bookProduct } = useMutation({
+  key: ['book-item'],
   keys: (product) => [['items'], ['items', product.id]],
   mutation: async (product: ProductListItem) => {
     await delay(Math.random() * 1000 + 200)

src/entry-options.ts

@@ -0,0 +1,7 @@
+import type { EntryNodeKey } from './tree-map'
+import type { _ObjectFlat } from './utils'
+
+/**
+ * Key used to identify a query. Always an array.
+ */
+export type UseEntryKey = Array<EntryNodeKey | _ObjectFlat>

src/index.ts

@@ -17,7 +17,10 @@ export { defineQuery } from './define-query'
 // export { type UseQueryKeyList } from './query-keys'
 
 export {
-  type UseQueryKey,
+  type UseEntryKey,
+} from './entry-options'
+
+export {
   type UseQueryOptions,
   type UseQueryOptionsWithDefaults,
 } from './query-options'

src/plugins/invalidate-queries.ts

@@ -1,16 +1,16 @@
 /**
  * @module @pinia/colada/plugins/invalidate-queries
  */
-import type { UseQueryKey } from '@pinia/colada'
+import type { UseEntryKey } from '@pinia/colada'
 
 export interface UseMutationOptionsInvalidateQueries<TResult, TVars> {
   /**
    * Keys to invalidate if the mutation succeeds so that `useQuery()` refetch if used. Only available if
    * `@pinia/colada/plugins/invalidate-queries` is installed.
    */
   invalidateKeys?:
-    | UseQueryKey[]
-    | ((data: TResult, vars: TVars) => UseQueryKey[])
+    | UseEntryKey[]
+    | ((data: TResult, vars: TVars) => UseEntryKey[])
 }
 
 declare module '@pinia/colada' {

src/query-options.ts

@@ -1,6 +1,5 @@
 import { type InjectionKey, type MaybeRefOrGetter, inject } from 'vue'
-import type { EntryNodeKey } from './tree-map'
-import type { _ObjectFlat } from './utils'
+import type { UseEntryKey } from './entry-options'
 import type { QueryPluginOptions } from './query-plugin'
 import type { ErrorDefault } from './types-extension'
 
@@ -9,11 +8,6 @@ import type { ErrorDefault } from './types-extension'
  */
 export type _RefetchOnControl = boolean | 'always'
 
-/**
- * Key used to identify a query. Always an array.
- */
-export type UseQueryKey = Array<EntryNodeKey | _ObjectFlat>
-
 /**
  * Context object passed to the `query` function of `useQuery()`.
  * @see {@link UseQueryOptions}
@@ -59,7 +53,7 @@ export interface UseQueryOptions<TResult = unknown, TError = ErrorDefault> {
    * })
    * ```
    */
-  key: MaybeRefOrGetter<UseQueryKey>
+  key: MaybeRefOrGetter<UseEntryKey>
 
   /**
    * The function that will be called to fetch the data. It **must** be async.

src/query-store.ts

@@ -12,7 +12,8 @@ import {
 } from 'vue'
 import { stringifyFlatObject } from './utils'
 import { type EntryNodeKey, TreeMapNode } from './tree-map'
-import type { UseQueryKey, UseQueryOptionsWithDefaults } from './query-options'
+import type { UseEntryKey } from './entry-options'
+import type { UseQueryOptionsWithDefaults } from './query-options'
 import type { ErrorDefault } from './types-extension'
 import type { defineQuery } from './define-query'
 
@@ -152,7 +153,7 @@ export const useQueryCache = defineStore(QUERY_STORE_ID, () => {
   }
 
   function ensureEntry<TResult = unknown, TError = ErrorDefault>(
-    keyRaw: UseQueryKey,
+    keyRaw: UseEntryKey,
     options: UseQueryOptionsWithDefaults<TResult, TError>,
   ): UseQueryEntry<TResult, TError> {
     if (process.env.NODE_ENV !== 'production' && keyRaw.length === 0) {
@@ -187,7 +188,7 @@ export const useQueryCache = defineStore(QUERY_STORE_ID, () => {
    * @param options.refetch - if true, it will refetch the data
    */
   function invalidateEntry(
-    key: UseQueryKey,
+    key: UseEntryKey,
     {
       refetch: shouldRefetch = true,
       exact = false,
@@ -310,7 +311,7 @@ export const useQueryCache = defineStore(QUERY_STORE_ID, () => {
 
   // TODO: tests, remove function version
   function setQueryData<TResult = unknown>(
-    key: UseQueryKey,
+    key: UseEntryKey,
     data: TResult | ((data: Ref<TResult | undefined>) => void),
   ) {
     const entry = caches.get(key.map(stringifyFlatObject)) as
@@ -331,7 +332,7 @@ export const useQueryCache = defineStore(QUERY_STORE_ID, () => {
   }
 
   function getQueryData<TResult = unknown>(
-    key: UseQueryKey,
+    key: UseEntryKey,
   ): TResult | undefined {
     const entry = caches.get(key.map(stringifyFlatObject)) as
       | UseQueryEntry<TResult>

src/use-mutation.ts

@@ -1,7 +1,7 @@
 import { computed, shallowRef } from 'vue'
-import type { ComputedRef, ShallowRef } from 'vue'
+import type { ComputedRef, MaybeRefOrGetter, ShallowRef } from 'vue'
 import { useQueryCache } from './query-store'
-import type { UseQueryKey } from './query-options'
+import type { UseEntryKey } from './entry-options'
 import type { ErrorDefault } from './types-extension'
 import { type _Awaitable, noop } from './utils'
 
@@ -11,8 +11,8 @@ import { type _Awaitable, noop } from './utils'
  * @internal
  */
 type _MutationKeys<TVars, TResult> =
-  | UseQueryKey[]
-  | ((data: TResult, vars: TVars) => UseQueryKey[])
+  | UseEntryKey[]
+  | ((data: TResult, vars: TVars) => UseEntryKey[])
 
 /**
  * The status of the mutation.
@@ -69,6 +69,8 @@ export interface UseMutationOptions<
    */
   mutation: (vars: TVars, context: NoInfer<TContext>) => Promise<TResult>
 
+  key?: MaybeRefOrGetter<UseEntryKey>
+
   // TODO: move this to a plugin that calls invalidateEntry()
   /**
    * Keys to invalidate if the mutation succeeds so that `useQuery()` refetch if used.

src/use-query.ts

@@ -13,8 +13,8 @@ import {
 import { IS_CLIENT, computedRef, useEventListener } from './utils'
 import { type _UseQueryEntry_State, useQueryCache } from './query-store'
 import { useQueryOptions } from './query-options'
+import type { UseEntryKey } from './entry-options'
 import type {
-  UseQueryKey,
   UseQueryOptions,
   UseQueryOptionsWithDefaults,
 } from './query-options'
@@ -176,9 +176,9 @@ export function useQuery<TResult, TError = ErrorDefault>(
  * @returns - the computed key
  */
 function _computedKeyWithWarnings(
-  key: MaybeRefOrGetter<UseQueryKey>,
+  key: MaybeRefOrGetter<UseEntryKey>,
   warnChecksMap: WeakMap<object, boolean>,
-): () => UseQueryKey {
+): () => UseEntryKey {
   const componentInstance = getCurrentInstance()
   // probably correct scope, no need to warn
   if (!componentInstance) return () => toValue(key)