@pinia/colada

Pinia Colada (WIP)

The missing data fetching library for Pinia

This is a more complete and production-ready (not yet!) version of the exercises from Mastering Pinia.

[!WARNING] Pinia Colada is still experimental and not ready for production. New versions might introduce breaking changes. Feedback regarding new and existing options and features is welcome!

Pinia Colada is an opinionated yet flexible data fetching layer on top of Pinia. It's built as a set of pinia plugins, stores and composables to benefit from Pinia's features and ecosystem. Pinia Colada has:

• ⚡️ Automatic caching: Smart client-side caching with request deduplication
• 🗄️ Async State: Handle any async state
• 📚 Typescript Support: Fully typed with Typescript
• 💨 Bundle Size: Small bundle size (<2kb) and fully tree-shakeable
• 📦 Zero Dependencies: No dependencies other than Pinia
• ⚙️ SSR: Server-side rendering support

Installation

npm install pinia @pinia/colada

Install the plugins for the features you need:

import { createPinia } from 'pinia'
import { QueryPlugin } from '@pinia/colada'

app.use(createPinia())
// install after pinia
app.use(QueryPlugin, {
  // optional options
})

Usage

<script lang="ts" setup>
import { useRoute } from 'vue-router'
import { useMutation, useQuery } from '@pinia/colada'
import { updateContact as _updateContact, getContactById } from '~/api/contacts'

const route = useRoute()

const { data: contact, isFetching } = useQuery({
  // recognizes this query as ['contacts', id]
  key: () => ['contacts', route.params.id],
  query: () => getContactById(route.params.id),
})

const { mutate: updateContact } = useMutation({
  // automatically invalidates the cache for ['contacts'] and ['contacts', id]
  keys: ({ id }) => [['contacts'], ['contacts', id]],
  mutation: _updateContact,
})
</script>

<template>
  <section>
    <ContactCard
      :key="contact.id"
      :contact="contact"
      :is-updating="isFetching"
      @update:contact="updateContact"
    />
  </section>
</template>

License

MIT

Changelog

0.7.0 (2024-07-26)

⚠ BREAKING CHANGES

• rename type UseEntryKey to EntryKey
• the exported type 'UseQueryKey' is replaced by the more generic type 'UseEntryKey', which will be also used to type mutations

Features

• debug plugin (8fde25b)
• expose plugin types (83ef198)
• mutation: allow passing mutation variables to mutation key getter (bc8a47f)
• retry plugin (0d837a2)
• support plugins and deprecate QueryPlugin in favor of PiniaColada (bde53d9)
• use-query: Add enabled option (#43) (1b755c5)
• wip: add gcTime (#29) (56659d1)

Bug Fixes

• gcTime on defined queries (#50) (82df409)
• query: query refresh on defineQuery output composable call (28a3ec1)
• trigger nested actions (7e3a9f6)

Reverts

• Revert "refactor: add a stale getter" (6e059f4)

Code Refactoring

• rename type 'UseQueryKey' to 'UseEntryKey' (6a32d89)
• rename type UseEntryKey to EntryKey (8110feb)