Pinia Colada Documentation

Query keys are hierarchical. You can nest keys to create relationships between queries. This allows you to invalidate a broad group of queries by matching a prefix (root key) or be more specific by including more segments.

Matching Rules:

• ['doc', 2] and ['doc', '2'] are different.
• In objects, undefined is stripped out (e.g., ['doc', { a: undefined }] matches ['doc', {}]), but null is preserved.
• Arrays are partially matched: ['doc', ['a', 'b']] matches ['doc', ['a']] but not ['doc', ['a', 'b', 'c']].

// gets the product with all its details
useQuery({
  key: () => ['products', productId.value],
  query: () => getProductById(productId.value),
})

// gets a product summary suited for searches
useQuery({
  key: () => ['products', productId.value, { searchResult: true }],
  query: () => getProductSummaryById(productId.value),
})

// Invalidating the root key ['products', productId.value] 
// will invalidate both the full product and the search summary.
queryCache.invalidateQueries({ key: ['products', productId.value] })

Unlike Nuxt's native useFetch, Pinia Colada's useQuery does not require an explicit await for Server-Side Rendering (SSR) to work.

Automatic SSR

useQuery uses onServerPrefetch internally. This means:

1. On the server, useQuery registers via onServerPrefetch.
2. The query runs and awaits during the server-side rendering process.
3. Data is serialized to the payload and hydrated on the client.

When to use await

You should still use await with useQuery if you want to block client-side navigation until the data is loaded. Without await, the page renders immediately and shows loading states while the data populates.

const { data, refresh } = useQuery({
  key: ['products'],
  query: () => $fetch('/api/products'),
})
// Block navigation until products load
await refresh()

// Pinia Colada: no await needed, SSR works automatically
const { data } = useQuery({
  key: ['products'],
  query: () => $fetch('/api/products'),
})

Entry extensions are properties stored on entry.ext that become available on the objects returned by useQuery() and useMutation().

Implementation Rules:

1. Use the extend action: You should only add new keys to entry.ext during the extend action. This action is called only once per entry and is shared across all plugins.
2. Do not replace the object: Do not assign a completely new object to entry.ext; instead, add properties to it.
3. Define keys early: You cannot add new keys to entry.ext later (e.g., in fetch or setEntryState). All keys must be defined during extend so they are available on the return value from the start.
4. Reactive extensions: When defining reactive extensions (like shallowRef), ensure they are created inside scope.run() so they are properly disposed of when the entry is removed.

TypeScript Augmentation:

Augment UseQueryEntryExtensions or UseMutationEntryExtensions to make these fields visible to consumers. You must preserve all generic parameters.

// Example: Adding a reactive field to a Query
import { type PiniaColadaPlugin } from '@pinia/colada'

export function PiniaColadaFeaturePlugin(): PiniaColadaPlugin {
  return ({ queryCache, scope }) => {
    queryCache.$onAction(({ name, args }) => {
      if (name === 'extend') {
        const [entry] = args
        scope.run(() => {
          entry.ext.myField = shallowRef<string>('initial value')
        })
      }
    })
  }
}

declare module '@pinia/colada' {
  interface UseQueryEntryExtensions<TData, TError, TDataInitial> {
    myField: ShallowRef<string>
  }
}

Metadata is stored in two distinct locations within a query entry:

1. entry.meta: The resolved value. This is the result of the meta function/ref, computed once when the entry is created.
2. entry.options.meta: The original value. This contains the raw function, ref, or object passed into the useQuery options.

Use entry.meta for logic that needs the actual data, and entry.options.meta if you need to inspect the original configuration.

import { useQueryCache, useQuery } from '@pinia/colada'

useQuery({
  key: ['time'],
  query: () => fetch('/api/time').then((r) => r.json()),
  meta: () => ({ timestamp: Date.now() }),
})

// ---cut-start---
const queryCache = useQueryCache()
// ---cut-end---

// In your plugin
queryCache.$onAction(({ name, after, args }) => {
  if (name === 'extend') {
    const [entry] = args
    console.log(entry.meta) // { timestamp: 1234567890 }
    console.log(entry.options?.meta) // [Function: metaFn]
  }
})